A.C.E. 2

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 2 / ACE CD 2.iso / FILES / UTILS / JACOSUB.LHA / JACOsub / documentation / JACOsub.doc < prev next >

Wrap

Text File | 1995-03-19 | 32.4 KB | 709 lines

JACOsub: video titling software for professionals version 2.1 Timed Script Editor and Player A Product from Unicorn Research Corporation This file contains information about running the JACOsub software. For a general overview (installation, compatibility, etc.), please refer to the file Overview.doc. JScripts doc contains the complete script format specification, QuickRef.doc is a quick summary of JScripts.doc, FAQ is a list of frequently asked questions, ARexx doc contains information about ARexx communications, and Register.doc contains registration information. RUNNING THE PROGRAM =================== Workbench --------- Just click twice on the JACOsub icon to start the program. Skip to the "Menu" section below. Shell ----- The Shell command for running JACOsub is simply jacosub [-switches] [scriptname] Command arguments are optional. Scriptname is the name of the script to play. If you specify ONLY the root name of your script (that is, with no .extension), JACOsub will look for the following 5 files: scriptname.js (JACOsub script) scriptname.tts (TurboTitle script) scriptname.pjs (Phoenix Japanimation Society script) scriptname.tim (generic timed script [actually same as .pjs]) If more than one of these are found, the newest one will be read in. Additionally, a compiled script of the same name (with the extension .jsc) will also be loaded if it is newer than the script you specified. JACOsub optionally saves its compiled script so that it will load up quickly in the future (it can take a few minutes to compile a longish script). The compiled script is typically over 3 times the size of the uncompiled version. Default behavior is for this automatic saving to be disabled, because you are likely to be fiddling with your script, which will require a recompile anyway. If you DO specify one of the above extensions in your script name, then JACOsub will attempt to load that specific script, plus the compiled if it exists and is newer. Switches: -config lets you specify a configuration file. The file name must appear following a space after the -config switch. If this switch is omitted, JACOsub will look for the file JACOsub.cfg in the current directory. -register takes you through the registration procedure. You will be asked for your name and registration code. After entering these, the program will permanently modify itself to reflect your ownership. Some features will be unlocked, and the script play display will not have that little logo in the lower right corner. See the "Shareware Notice" and "Commercial License" sections near the end of this document for details on obtaining a registration code. This switch is the same as clicking twice on the "register" icon. -trace displays a trace of program execution during initializations. If JACOsub crashes when loading, try this switch, then write to the author and describe what was displayed. -any other switch causes a help message to be displayed. During script compilation, JACOsub will inform you of its progress as well as any errors that it finds in your script. Example ------- To see how it all works, run the demo script (called demo.js). There are three ways you can do this: 1) From JACOsub: After starting JACOsub either from the shell or from Workbench, press right-Amiga-O Open a script, and select demo.js from the file requester. 2) From a Shell: Just make sure that demo.js, idemo.js, and JACO.bbm are in your scripts directory, and type this command: run jacosub demo 3) From Workbench: Click ONCE on the demo.js icon. Then, while holding down the SHIFT key, click twice on the JACOsub icon. Once the script is loaded, press right-Amiga-P to play it. It will be compiled first if needed. THE EDITOR WINDOW ================= The first thing you see when you run JACOsub is the editor window. Besides the pull-down menus, there are several operations that can be done with the keyboard and the mouse: - The Shift-Up and Shift-Down arrow keys will page the screen up and down. - The Shift-Left and Shift-Right keys will skip the cursor over words. - Clicking the mouse on the display will reposition the text cursor. - Holding down the mouse button on the top line, bottom line, left column, or right column of the display will cause the display to scroll. - Double-clicking the mouse on a line starts a block definition. Double- clicking somewhere else expands the block to the new position. Double- clicking again starts over with a new block definition. - The function keys F1-F10 may be defined to insert often-used strings. Set these with the "FKey macro" selection in the "Config" menu. - Press right-Amiga-T to toggle the cursor between the first line and last line of your script. - Press right-Amiga-] to toggle the cursor between the beginning and end of the current line. PULL-DOWN MENUS =============== There are five pull-down menus available in JACOsub, each with several selections. Many selections have a keyboard shortcut; these shortcuts are displayed alongside the selections. File -- file operations ----------------------- New Remove current script from memory. Open Open a new script and load it into the editor. The file must be a legal script type; that is, the name must end in .js, .tts, .pjs, or .tim. Insert file Insert a file ahead of the current line. You can use this selection to load up any ASCII file that is not an actual script. Save Save the script using the current name. Save as Save the script under another name. Save block Save the current highlighted block to a file. Print block Print the current highlighted block to device prt:. View IFF file Preview pictures in the graphics directory. About Display some information about JACOsub & free RAM. Quit Exit the program. Edit -- editing operations -------------------------- Block start Mark the beginning of a block at the current line. Block end Mark the end of a block at the current line. Clear block Remove all block markings. Select all Mark all lines in the script as a block. Cut block Cut currently-marked block from the script, and save it in the clip buffer. Copy block Copy currently marked block into clip buffer. Insert block Insert clip contents into script ahead of the current line. Delete line Delete current line under the cursor. Undelete line Insert last deleted line ahead of current line. Jump to line Enter a line number to jump to. Beg/End of line Toggle cursor between beginning and end of line. Top/End of file Toggle cursor between beginning and end of script. Overstrike Toggle between insert and overstrike editing modes. Search -- searching and replacing --------------------------------- Find Search for a string. Replace Search and replace a string (singly or multiply). Go next find/rpl Go to next search or replace occurrence. Script -- timing and other script operations -------------------------------------------- IMPORTANT: There are some operations where you are asked to enter numbers. In all of JACOsub's numerical handling, numbers after a decimal point DO NOT represent fractions of a second. They represent whole time units. 12.4 and 12.004 mean the same thing: 12 seconds plus 4 time units. The number of time units per second is determined by your #TIMERES setting in your script. Default is 30/second if not specified. Suppose you are using 100 units/second and want to specify 0.4 seconds. You must specify 40 UNITS. That is .40, not .4 (which would be 4 units, or 0.04 seconds). Time block Time the lines in a block that have timing numbers. Ramp block Ramp-adjust times in a block for drift. Shift block Shift all times in a block up or down. Time-divide block Equalize the differences between start times in a block, so that all titles have the same duration. Auto-endtime Intelligently adjust title durations in a block, depending on character length, default minimum duration, and next-title start time. Time format & resolution (submenu) H:MM:SS.FF Convert times in a block to H:MM:SS.FF format. @Frame counts Convert times in a block to @FFFFFFF format. New counts/sec Change time resolution & format over entire script. Resolve #R's & #S's Resolve times for all #R and #S commands, and remove the #R and #S commands from the script. Insert dummy times Insert dummy start and stop times in front of every untimed non-blank uncommented line in a block. View play ramp&shift Show the current script play ramp & shift setting. Play script Play the script, compiling first if needed. Pressing ESC during compilation returns you to the editor. Prior to playing, you may adjust several settings: play mode (normal, running clock, or manual step), ramp & shift values, and begin time. Play block Play only the highlighted block. View line See what current line will look like during play. MouseMove line Position a title with the mouse (WYSIWYG). Other titles and graphics which are timed to appear on the screen at the same time as the selected title, will also be displayed for reference, if the selected line is inside a highlighted block. Compile script Compile the script (this is automatically done when you play a script, so you will rarely need this). You can abort long compilations by pressing ESC. Time overlap warn Warn during compile if the time range for any line overlaps the time range for the previous line. Save compiled Dump the compiled script data structures to a file. The file will have the extension .jsc on its name. Config -- configuring JACOsub ----------------------------- NOTE: Selecting "Save" in any Config requester will save the entire program configuration, not just the information in that requester. The software must be registered to save program configurations. General settings Set general configuration parameters (these settings are listed under "General Settings" in the Configuration File section below. Fonts and Function Keys have their own menu selections. FKey macros Set function key macro strings. Titling Fonts View or set currently-loaded fonts to be used for playing scripts. The fonts shown are usually those that were initially loaded, unless they were overridden by your script. Playing / video Set play behavior parameters (includes both the "Play Behavior" and "video" settings described in the Configuration File section below). Load config Load a new configuration. Save config Save the program configuration (software must be registered). NOTES ABOUT PLAYING SCRIPTS =========================== Play modes ---------- There are three modes; real-time, real-time with a running clock display, and step-play. real-time or normal: This is the normal play mode to use when making a final master. running clock: This mode puts a small screen in front of the video title display, showing a digital clock plus ramp and shift information. You can drag the clock up and down. JACOsub will raise all bottom- positioned text a little bit so that the clock won't cover up too much. If it is covering too much for your taste, you can temporarily raise this text by inserting a command like #D VB32 in your script (see "Compiler Commands" in the file JScripts.doc). The clock display may appear to run erratically at times. This happens when JACOsub is too busy generating images in background video buffers and cannot update the clock display as frequently. Do not worry; internal timing is not affected. The clock display is mainly for using with a blank script so you can record a clock on your video for manual (that is, highly accurate) timing purposes. step play: This mode allows you to step manually through your script to see how each screen will appear during real-time play. The spacebar steps forward 1 screen, and backspace steps backward up to 3-5, depending on how many video buffers you have set up. On-the-fly time shift adjustments --------------------------------- You may adjust the absolute time shift during play by pressing the + key to increase the times (i.e. delay them) and - to decrease the times. The amount of shift is changed by the ramp&shift increment you set up prior to playing the script. After your script is finished playing, you may select the "View play ramp&shift" menu to view the settings. On-the-fly ramp drift adjustments --------------------------------- During play, you can make ramp time adjustments on the fly. Suppose you have the ramp&shift increment set to 0.10 sec. Pressing the down-arrow key will decrease the ramp time adjustment by 0.1 seconds, and pressing the up-arrow key will increase it by 0.1 seconds. THE CHANGE WILL OCCUR AT THE TIME-POINT WHERE YOU CHANGED IT. For example, if the script play is 20% complete (1/5 done) and you pressed the up-arrow key, time events would be increased by 0.1 seconds AT THAT TIME -- this would increase the ENDING ramp time by five times that amount (i.e. 0.5 seconds) because the play is only 1/5 complete at the time you made the change. The running clock display will show you the ENDING ramp time. After your script finishes playing, you may select "View play ramp&shift" to view the settings. Beware of adjusting ramp time near the beginning of the script! Doing this too early in the play will result in a drastically huge change at the end (for example, if the playing is 1/1000 complete, a 0.1 sec change in ramp time will result in a 100-second change near the end!). Don't be disconcerted by the Ramp display on the running clock; as stated before, it shows the ENDING ramp adjustment. On-the-fly ramp adjusting is *wonderful* when you get used to it. Usually you will only have to make two or three adjustments during the entire script play, whereas straight time shift adjustments have to be done many times at regular intervals to keep the script in sync with the video. >> If you find that you need more than 10 seconds of ramp adjustment per 30 minutes of script, then your genlock is having an adverse affect on your system clock. GET THIS FIXED. Do not use JACOsub to "fix" the problem with a bigger ramp adjustment; you are only CURING THE SYMPTOM of a serious problem, not the cause! Besides, if a ramp adjustment gets too large, an internal math overflow can occur, resulting in a sudden time-jump. If you need large ramps, get some technical support from your genlock vendor. << OPTIONAL CONFIGURATION FILE =========================== JACOsub will set its own defaults for parameters that are omitted in the file called JACOsub.cfg (and also if the file doesn't exist). You really will never need to edit the config file directly, but you can if you want to. You may change the configuration from any of the "Config" menu selections, and save your changes (saving the config file is possible only when the software has been registered). When running JACOsub from a Shell, you can specify which config file you want using the -config commandline switch, or you can run JACOsub from whichever directory that contains the desired config file. Each line in the JACOsub.cfg file may be: a blank line, a comment (must begin with a # character), or a setting. Settings have the following form: SETTING <argument1> <argument2> ... Here are the settings and their possible arguments. They may be either uppercase or lowercase. The default settings indicated are what you get if you omit a particular setting from your config file. Parameters inside brackets [] are optional. General Settings ---------------- AUTOENDTIME <overall (milliseconds)> [additional (millisec/character)] [changed in AutoEndtime or Time Script menu selection] When timing a script or performing the Automatic End Time adjustment feature, JACOsub needs to know what default time duration you want for your titles. <overall> is the minimum duration in milliseconds. Titles appear on the screen for at least this length of time (this duration is shortened during timing if you raise another title before the current title has expired). [additional] is the additional amount of time to display the title, expressed in milliseconds per character. The character count of the title does not include directives, embedded comments, or embedded escape codes - only the title text itself. Default: AUTOENDTIME 2000 33 DIRECTIVE <directive string> [changed in the General Settings menu selection] Sets the initial global D directive for all scripts. Don't be scared by the huge default string shown below; yours won't ever look like this. See the "Directive" section in the format specification documentation JScripts.doc for complete understanding. Anything you set here represents a *change* to the default string below, not a replacement. Default: DIRECTIVE HL1HR99VH100VT16VB16JCJBFFDF0FO0FSSE0SNCF3CB0CP0CS0:0:2W1 DURATIONWARN <number of seconds> [changed in the General Settings menu selection] If you inadvertently set a title's start and stop times so that its duration is too long, you might want JACOsub to warn you about it when your script is compiled. This problem sometimes occurs when compiling TurboTitle scripts, where some "null" lines can have a start time of 0 and a stop time of 9 hours! This setting lets you set the minimum title duration that will trigger a warning during script compilation. Default: DURATIONWARN 120 EDITORWINDOW <LeftEdge> <TopEdge> <Width> <Height> [changed with the editor window resizing gadget] This determines the initial position and size height of the editor window. Minimum window size is 420x150. To change this setting while using JACOsub, simply use the mouse to change the size of the editor window and save the program configuration. Default: EDITORWINDOW 0 2 640 198 FKEY <key number> <macro string> [changed in the Fkey macro menu selection] You may set any of the 10 function keys to send a string (up to 80 characters) to the editor. This is useful to keep from typing commonly used strings over and over again. <key number> should range from 1 to 10, and you should not have a comment behind the macro string or it will be included as part of the string. Default: FKEY 10 9:00:00.00 9:00:00.0 D (This is useful for inserting dummy times in front of lines) Function keys 1 - 9 are not set. FONT <n> <fontname.font> <size> [CLEAN or QUICK&DIRTY] [changed in the Title Fonts menu selection or changed by your script] Sets font <n> to <fontname.font> which is <size> pixels high. <n> must range from 0 to 9. The font should be a proportional-spaced color font, although you can use any font. You will normally NEVER need the last argument. The CLEAN argument (default for color fonts with overlapping characters if omitted) tells JACOsub to display this font "cleanly," that is, to avoid an artifact of the Amiga's text rendering operation that results in color interference problems when rendering fonts with overlapped characters (such as the JACOsub 36 and 32 fonts). With CLEAN, only color 3 text will be rendered quickly; other colors will be rendered one character at a time instead of a line at a time. QUICK&DIRTY forces the font to render quickly, with the resultant color interference problems. QUICK&DIRTY is the default for mono-color fonts and color fonts without overlapping characters. Defaults: FONT 0 JACOsub.font 36 (primary font) FONT 1 JACOsub.font 32 (secondary font) FONT 2 JACOsub.font 32 FONT 3 JACOsub.font 32 FONT 4 JACOsub.font 32 (Note: fonts 4 through 9 are FONT 5 JACOsub.font 32 not available unless the software FONT 6 JACOsub.font 32 has been registered.) FONT 7 JACOsub.font 32 FONT 8 JACOsub.font 32 FONT 9 JACOsub.font 32 Important point about fonts: Color fonts should be designed so that bitplane 0 (color 1) contains the font face imagery, while bitplane 1 (color 2) contains the outline and dropshadow imagery. JACOsub assumes all color fonts are designed this way. This design is necessary for face color control and rendering efficiency. The TurboTitle font was not designed this way, so it will look all wrong unless you use a font editor to reassign the bitplanes. GENLOCK <NONE or SUPERGEN or GVP or TOASTER> [changed in the General Settings menu selection] Specifies how to interpret genlock fader control commands in a script (see the "Directive" section in the format specification documentation JScripts.doc). NONE will cause such commands to be ignored. Otherwise JACOsub will attempt to control the type of genlock specified. Currently only the Digital Creations SuperGen is supported, using supergen.library version 2.0 or higher. GVP genlocks can cause crashes when a program tries to load an IFF file without using GVP's own proprietary file loader. Setting GENLOCK to GVP will cause JACOsub to look for a script called gvpfade.jsrx for genlock fading (see the file ARexx.doc for details), and it will also cause a compile warning to be issued if your script tries to load an IFF file. The script will still compile properly, however. TOASTER specifies the NewTek video toaster, which like the GVP must be controlled through ARexx, and requires a script called toasterfade.jsrx. Default: GENLOCK NONE GRAPHICPATH <path for graphics files> [changed in the General Settings menu selection] Tells JACOsub the directory where it should expect to find IFF graphics. Default: the "scripts" directory under the current directory. GRAPHICPATH scripts MAKEBACKUP <YES or NO> [changed in the General Settings menu selection] If set to YES, JACOsub will copy your original script on your disk to the T: directory before saving an updated version. Under normal AmigaDOS configurations, the T: directory is on the ramdisk. Default: MAKEBACKUP NO SAVECOMPILED <YES or NO> [changed in the General Settings menu selection] Tells JACOsub whether or not to save compiled versions of your scripts automatically. Compiled scripts load up quicker than raw ASCII scripts, but they consume more disk space. You are not likely to need this setting. Default: SAVECOMPILED NO SCRIPTPATH <script path> [changed in the General Settings menu selection] Tells JACOsub the directory where it should expect to find scripts. Default: the "scripts" directory under the current directory. SCRIPTPATH scripts Play Behavior Settings ---------------------- ANTIALIASCOLOR <color number> [changed in the Playing / Video menu selection] This setting is relevant only when JACOsub generates its own outlines around mono-color fonts (which is not the case with the JACOsub distribution fonts). The color you specify here will be used inside the font outline, 1 pixel to the left and right of the font image. This color should be neutral gray or a half-intensity face color, which you can set with the PALETTE setting below. The default is color 2, which should *always* be black. Because outlines are also black, a setting of 2 results in no anti-aliasing when font outlines are generated (it's also faster). Default: ANTIALIASCOLOR 2 CLOCKHEIGHT <NORMAL or TALL> [changed in the Playing / Video menu selection] The running clock display can be made twice as tall as normal. This setting is useful if you have trouble reading the clock display during frame-stepping in your video tape. Default: CLOCKHEIGHT NORMAL RAMPSHIFTINCR <milliseconds> [changed prior to playing a script] This setting determines the initial on-the-fly ramp and shift adjustment increment. Ramp and shift corrections made during script play will be changed by this amount. You may change this increment from the program when you try to play a script. Default: RAMPSHIFTINCR 100 # 100 milliseconds = 1/10 second SHADEPATTERN <line1> <line2> <line3> <line4> [changed in the Playing / Video menu selection] Sets the shade pattern for the CS directive (see the "Directive" section in JScripts.doc). The pattern is bit mask 16 pixels wide and 4 scanlines high, specified by line1-line4, which must be 16-bit hexadecimal numbers (these numbers represent each scan line for the mask). The default is two solid horizontal scanlines followed by two blank scanlines, because this seems most reliable for all genlocks. Some genlocks will grossly distort the video image if you try to specify a complex mask like the default which turns on every other dot. For other genlocks like the SuperGen or GVP, this mask results in a beautiful transparent video darkening effect. The hexadecimal paramters may be uppercase or lowercase. Default (vertical lines every other pixel): SHADEPATTERN AAAA AAAA AAAA AAAA TIMEFONT <fontname.font> <size> [changed in the Playing / Video menu selection] Sets the time-font. This font is used for the running clock display. It should be a fixed-width, mono-color font, sufficiently large to be legible when recorded on your videotape. MAXIMUM <size> is 24. If the specified font is not found, the Topaz 9 ROM font will be used. Default: TIMEFONT JACOsub.font 18 USEBLITTER <YES or NO> [changed in the Playing / Video menu selection] This setting is difficult to explain. JACOsub generates a new video frame for each time event specified in a script. If the time ranges for different titles overlap, then some titles must exist on more than one frame in order to endure through the overlapping time events from other titles. Generating the same text again and again on different frames might slow down the program, so JACOsub uses the Amiga blitter to duplicate text strings between video frames. This advantage in speed also has a disadvantage: If the text was initially generated over other imagery already on the screen (such as an IFF brush or a shaded rectangle background), a portion of this imagery will get blitted into the other frames along with the text. But suppose you did not want this imagery to survive into subsequent frames? You can disable blitter operations, forcing all text to be generated into each frame (instead of copying using the blitter), by specifying NO for this parameter. Regardless of this setting, the blitter is NOT used to copy text if IFF graphic backgrounds change between subsequent frames. Default: USEBLITTER YES Video Display Settings ---------------------- BITPLANES <number of bitplanes> [changed in the Playing / Video menu selection] Sets number of bitplanes per video buffer. 2 to the power of this number is the number of colors available. Maximum bitplanes is 2 if SUPERHIRES is set. You shouldn't need to set this greater than 4 (for 16 colors). Default: BITPLANES 2 # 2 bitplanes = 4 colors DISPLAYSIZE <width> <height> [changed in the Playing / Video menu selection] Sets the size of the playing display. <width> should be a multiple of 16, greater than or equal to 640. <height> should be greater than or equal to 400. If <width> is less than 800 and HRES (below) is set to SUPERHIRES, then <width> will be doubled internally. If <width> is greater than 800 and HRES is set to HIRES, then <width> will be halved. Default: DISPLAYSIZE 640 400 HRES <HIRES or SUPERHIRES> [changed in the Playing / Video menu selection] Sets display horizontal resolution mode. SUPERHIRES will work only if your Amiga has the complete ECS or AGA chipsets, and your AmigaDOS version is 2.0 or better. Otherwise, SUPERHIRES will be interpreted as HIRES, which is the default horizontal resolution for Workbench. Amigas with the ECS chipset are limited to 4 colors in superhires mode. Default: HRES HIRES PALETTE <n> <red> <green> <blue> [changed in the Playing / Video menu selection] Sets the red, green, and blue CRT beam intensities for color <n>. <n> may range from 0 to 15 (although the maximum used will be determined by the BITPLANES setting). <red>, <green>, and <blue> may range from 0 (off) to 15 (maximum) although for NTSC friendliness you should probably not go beyond 13 or 14. This initial palette may be changed by your script (see the #P command), and it is active only when a script is playing. You cannot change the palette for the menu screen. Defaults (please give us feeback if you have better settings!): PALETTE 0 9 10 11 # background (transparent when genlocked) PALETTE 1 1 14 8 # ALTERNATE font face color PALETTE 2 0 0 0 # font outline/shadow color (SHOULD BE DARK) PALETTE 3 13 14 5 # PRIMARY font face color PALETTE 4 14 0 0 # red - remaining settings are arbitrary PALETTE 5 14 14 0 # yellow PALETTE 6 0 14 0 # green PALETTE 7 0 14 14 # cyan PALETTE 8 0 0 14 # blue PALETTE 9 14 0 14 # magenta PALETTE 10 14 10 5 # orangey PALETTE 11 3 3 3 # gray shades... PALETTE 12 6 6 6 PALETTE 13 9 9 9 PALETTE 14 12 12 12 PALETTE 15 14 14 14 TOPLEFT <x offset> <y offset> [changed immediately prior to playing a script] If your play screen is centered on your RGB monitor, it will likely NOT be centered when you record the video signal on a VCR or view this signal on a television screen. The TOPLEFT setting determines where the top left corner of the play screen will be. YOU SHOULD NOT SET THIS YOURSELF in JACOsub.cfg. JACOsub will let you center the screen before playing your script (AmigaDOS 2.0+ only), and you can save the settings later by selecting "Save config" from the Config menu. This setting works only under AmigaDOS 2.0 and above. Under 1.3, you must first center your Workbench screen on your television using Preferences, before running JACOsub. Default: The top left corner of your Workbench screen is used for this setting. VIDEOBUFFERS <number of buffers> [changed in the Playing / Video menu selection] Sets the number of video buffers to use for building displays. Minimum number allowed is 3, maximum is 5. Set to 3 if you are low on CHIP RAM, of if your script doesn't do time-consuming complicated things (such as generate outlines around a screenful of text with a graphics backdrop). Increase the number of buffers ONLY if you notice that JACOsub is generating imagery on the visible screen (all image generation should take place in the background where you cannot see it). Default: VIDEOBUFFERS 4 End of JACOsub.doc. See JScripts.doc for details about scripts.